Share commentPrefix's rule in one place in LibCodeGenSlow - #107

Closes #73

What

bytes(comment).length == 0 ? "\n" : string.concat("\n", comment, "\n") was
pasted into all four …ConstantStringSlow builders in
test/lib/LibCodeGenSlow.sol. That is LibCodeGen.commentPrefix's body
character for character, in four places. The four copies now call one
commentPrefixSlow.

Keeping the reference independently derived

LibCodeGenSlow is the differential reference for LibCodeGen. Its value is
that it derives the expected output instead of restating the implementation, so
a shared design error shows up as a disagreement rather than moving both sides
at once. Lifting the pasted expression verbatim into a shared function would
have turned four restatements into one restatement — the same defect, better
factored — so that is not what this does.

commentPrefixSlow derives the prefix from the rule as stated in prose rather
than from the code that implements it. The rule is "a declaration is preceded by
one blank line always, and by a comment line only when there is a comment", so
the reference lists those lines and joins them, terminating each:

string[] memory lines = new string[](bytes(comment).length == 0 ? 1 : 2);
lines[0] = "";
if (lines.length == 2) {
    lines[1] = comment;
}
string memory prefix = "";
for (uint256 i = 0; i < lines.length; i++) {
    prefix = string.concat(prefix, lines[i], "\n");
}

LibCodeGen.commentPrefix chooses between two whole prefix literals. The
reference spells out neither of those literals, and states the line count and
the per-line text as separate facts. Neither side can be updated by pasting from
the other, which is the property the file exists to have.

lines[0] = "" is redundant in the sense that a fresh string[] element is
already the empty string. It is kept because the blank line is half the rule and
the array is where the rule is stated. M4 below breaks that line and the suite
reds, so it is load bearing for the tests as written, not decoration.

The library's @notice disclosed the copy as the one place the two sides state
the same rule. That is no longer what the file does, so the paragraph now
describes the line assembly.

Where this went past the issue's proposed fix

The issue asked to extract commentPrefixSlow and keep the docstring's
disclosure attached to it. Extracting alone would have left a verbatim
restatement, so the body was re-derived as above, and the disclosure was
replaced rather than moved — there is no longer a restatement to disclose. The
docstring on commentPrefixSlow says how its derivation differs from the
library's instead.

Tests

test/lib/LibCodeGen.commentPrefix.t.sol is new, next to its siblings in
test/lib/. Two literal assertions pin commentPrefixSlow's own two cases so
the reference is not held up only by agreeing with the implementation, and a
fuzz asserts LibCodeGen.commentPrefix(comment) == LibCodeGenSlow.commentPrefixSlow(comment) over 2048 comments. The four
builders' existing differential fuzzes cover the extraction not changing what
they emit.

QA

• Discriminating tests: testCommentPrefixSlowEmptyComment,
  testCommentPrefixSlowWithComment, testCommentPrefixMatchesSlow - each
  fails on base, verified by running
  nix develop -c forge test --match-path test/lib/LibCodeGen.commentPrefix.t.sol
  on the branch with the test written and commentPrefixSlow not yet added:
  the compile fails with Error (9582): Member "commentPrefixSlow" not found
  (full output below).
• Mutations applied: 8, all killed, full matrix with per-mutant failure counts
  and killing tests in the table below. ? 1 : 2 -> ? 2 : 2 ->
  testCommentPrefixSlowEmptyComment; lines[1] = comment -> lines[1] = ""
  -> testCommentPrefixSlowWithComment; drop the "\n" terminator in the join
  -> both literal pins; lines[0] = "" -> lines[0] = "X" -> both literal
  pins; loop i = 0 -> i = 1 -> both literal pins; and three mutants of
  LibCodeGen.commentPrefix itself (? "\n" -> ? "", drop the trailing
  "\n", == 0 -> != 0) each killed through testCommentPrefixMatchesSlow.
• Oracle: the rule as stated in prose in LibCodeGen.commentPrefix's docstring
  and in the forge fmt behaviour it exists for - one blank line always, a
  comment line only when there is a comment. The two literal assertions carry
  the expected strings written out, and commentPrefixSlow builds from the
  list of lines rather than from the implementation's expression, so neither
  the reference nor the tests take their expectation from LibCodeGen.
• Category check: the issue asks for one thing, the four pasted copies of
  commentPrefix's body at LibCodeGenSlow.sol:72,84,96,110 - covered, all
  four now call commentPrefixSlow, grep finds no remaining copy of the
  expression in the file. The issue's own proposed fix (extract and move the
  docstring disclosure) is covered and extended: the body is re-derived rather
  than lifted, so there is no restatement left to disclose.

Red first. With the test written and commentPrefixSlow not yet added,
nix develop -c forge test --match-path test/lib/LibCodeGen.commentPrefix.t.sol:

Compiler run failed:
Error (9582): Member "commentPrefixSlow" not found or not visible after argument-dependent lookup in type(library LibCodeGenSlow).
  --> test/lib/LibCodeGen.commentPrefix.t.sol:21:18:
   |
21 |         assertEq(LibCodeGenSlow.commentPrefixSlow(""), "\n");
   |                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The finding is a code-quality one — four copies of a rule that already agreed
with each other — so there is no behavioural red to show. The red is that the
shared function and the assertions that hold it did not exist. The mutation
matrix below is what demonstrates the new code is covered rather than merely
present.

Green after. nix develop -c forge test:
Ran 17 test suites: 137 tests passed, 0 failed, 0 skipped (137 total tests)
— 134 before this branch, plus the three new ones.

nix develop -c forge fmt --check exits 0, no files listed.

Mutation matrix. Each mutant: applied by sed, the edit proved to have
landed by a non-empty git diff before the suite ran (a pattern that matched
nothing aborts as INVALID rather than reading as "survived"), whole suite run,
git checkout to restore. Control run first: 137 passed / 0 failed. Every
mutant is killed; the counts are out of the same 137.

M1–M5 mutate the new reference and are killed by the new tests and by the four
builders' differentials. M6–M8 mutate the implementation the reference guards
and are killed through the differential, so the extraction did not cost the
suite any of the discrimination the four copies had.